/**
 * Copyright (C) 2013 DaiKit.com - daikit4gxt module (admin@daikit.com)
 *
 *         Project home : http://code.daikit.com/daikit4gxt
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.daikit.daikit4gxt.client.rpc;

import com.daikit.commons.shared.bean.BaseUser;
import com.daikit.commons.shared.exception.DkException;
import com.daikit.commons.shared.exception.authentication.DkHackingAttemptException;
import com.daikit.commons.shared.exception.authentication.DkUserLoggedChangedException;
import com.daikit.commons.shared.exception.authentication.DkUserNotAuthenticatedException;
import com.daikit.daikit4gxt.shared.bean.ConnectionData;
import com.daikit.daikit4gxt.shared.bean.ConnectionReturnData;
import com.google.gwt.user.client.rpc.RemoteService;


/**
 * This interface should be extended by your application RpcUser interface.<br>
 * You have to add the following annotation (or a similar one) to your RpcUser interface and add the corresponding URL
 * mapping in your servlet configuration.<br>
 * <br>
 * //@RemoteServiceRelativePath("../dispatcher/gwt-rpc/RpcUser")
 * 
 * @author Thibaut Caselli
 */
public abstract interface BaseRpcUser extends RemoteService
{

	/**
	 * This method should only be implemented if we need the mode without security
	 * 
	 * @param connectionData
	 * @return a {@link ConnectionReturnData}
	 * @throws DkException
	 */
	ConnectionReturnData connectWithoutSecurity(ConnectionData connectionData) throws DkException;

	/**
	 * This method should only be implemented if we need the mode without security. Else it should return a
	 * {@link DkHackingAttemptException }
	 * 
	 * @throws DkException
	 */
	void disconnectWithoutSecurity() throws DkException;

	/**
	 * This method is intended to be overridden if you want to change the type of the returned User.<br>
	 * This method should return the currently logged user (stored in server side session).<br>
	 * If you use an annex login application or a cookie mechanism you need to check that the User retrieved from the
	 * cookie session is the same than the User retrieved from the server session. <b>Many cases may appear :</b><br>
	 * <ul>
	 * <li>If the server side logged user is null and it is not possible to get a User from the cookie session you should
	 * redirect the user to the login page or throw a {@link DkUserNotAuthenticatedException}</li>
	 * <li>Else if the server side logged user if not null and different from the one retrieved from the cookie you need
	 * to throw a {@link DkUserLoggedChangedException}</li>
	 * <li>If the user retrieved from the server side session is the same than the user retrieved from the cookie session
	 * you can return it</li>
	 * <li>If the user retrieved from the server side session is Null and it is possible to retrieve the user from the
	 * cookie session you should update the server side user and return it</li>
	 * 
	 * @return the currently logged BaseUser.
	 * @throws DkException
	 */
	BaseUser getCurrentUser() throws DkException;

	/**
	 * This method is intended to be overridden if you want to change the type of the returned User.<br>
	 * This method is intended to be called after a call to {@link #getCurrentUser()} which throws a
	 * {@link DkUserLoggedChangedException}.
	 * 
	 * @return the currently logged BaseUser.
	 * @throws DkException
	 * @see {@link #getCurrentUser()}
	 */
	BaseUser getSynchronizedCurrentUser() throws DkException;

}
